Thanks for the pull request, and sorry for taking so long to respond! Like you said, it's pretty opinionated but I think it's overall an improvement.

Can you elaborate a bit more on the bind-mount syntax being used? Preferably with a single-line explanation of what it does, and a link to the relevant documentation? Just to explain these two lines.

RUN --mount=type=cache,target=/root/.cache/R/renv/cache
RUN --mount=type=bind,from=renv-cache,source=.,target=/root/.cache/R/renv/cache,rw \

Related to the above; I believe this assumes the container needs to be run as root? Or will this also work for images / containers running as a non-root user?

I'd also like to keep the "dynamically provisioning R library" section -- this is most useful for the "single image, multiple applications" approach to using Docker, whereas I think your proposed approach centers upon using unique images for each application. Correct me if I'm wrong!

Also worth pointing out that you don't explicitly install renv in the Dockerfile definitions, and instead rely on the renv bootstrap script to handle that for you.

Related to the above; I believe this assumes the container needs to be run as root? Or will this also work for images / containers running as a non-root user?

You're right, this would fail. So far I have only provisioned containers with the root user. I assume if I replace root with the relative $HOME path this should cover the custom user use case right?

I'd also like to keep the "dynamically provisioning R library" section -- this is most useful for the "single image, multiple applications" approach to using Docker, whereas I think your proposed approach centers upon using unique images for each application. Correct me if I'm wrong!

Yes my rewrite centers on this to follow the widely utilized 12 factor app principles https://12factor.net/build-release-run. Under these assumptions I would heavily discourage the use of dynamic provisioning for production use cases.

I could also see how it could be useful under a local development workflow where we for example have a monorepo with multiple R apps that need to run at the same time and we want to prevent long rebuilds. In this environment I still feel it would be much cleaner to have a single docker compose file in root with build statements that leverage either the cache or bind mount, where the cache mount would be faster for repeated builds and the bind mount would reduce the time of the first build if the host already had those packages.

I felt that these approaches should cover all use cases which is why I deleted that section, but if you feel that there are use cases I have not covered or that we should just offer an alternative way of reaching those I'll gladly reinstate the section.

Also worth pointing out that you don't explicitly install renv in the Dockerfile definitions, and instead rely on the renv bootstrap script to handle that for you.

Yes, I only ever containerized apps with renv pre-initialized and committed in the git repo where the container was built based on the git context. I struggled to come up with a use case where this is not the case. If you could let me know under which conditions this could happen I could make a more comprehensive hint.

Thanks for the PR! On reflection, I think my comments aren't really worth addressing -- your additions are an improvement on the existing documentation, and I like being able to advertise a single "best" way of doing things. I've merged it as is.

Thanks for the kind words! If you ever feel this lacks anything or any issues come up feel free to ping me, I'm more than happy to help out on anything docker related.